.. _example-phreeqc-basics-01:

01 - Results Visualization
==========================

One simulation, shown five different ways. This example is not about the
chemistry -- it reuses the cation exchange column of
:ref:`example-phreeqc-manual-11` -- but about what can be done with the
results once they exist.

A reactive transport run produces a table with three independent axes:
distance along the column, time, and chemical species. No single plot shows
all three, so every figure here is a decision about which one to collapse.
That choice is the subject.

.. raw:: html
   :file: study_ex1.html


Pick two of three
-----------------

.. figure:: SpeciesTimeEvolution.svg
   :alt: Chloride, sodium, potassium and calcium against pore volumes at one cell, with the analytical chloride
   :align: center

   **Fix the place, vary time.** Concentrations at the boundary cell against
   pore volumes -- the breakthrough curve, and the form in which a column
   experiment is measured. The analytical chloride is drawn with it as the
   check described in :ref:`example-phreeqc-manual-11`.

.. figure:: KCell_minus_TimeEvolution.svg
   :alt: Potassium as a colour map over distance and time
   :align: center

   **Keep both, drop the species.** Potassium over distance and time as a
   colour map: one species, the whole run. Fronts appear here as diagonal
   bands, and their slope is a velocity -- which is the thing neither a
   breakthrough curve nor a profile shows directly.

.. figure:: CationSpeciesSurface.svg
   :alt: Concentration surfaces of several species over distance and time
   :align: center

   **The same, as a surface.** Several species at once over the same two
   axes. Harder to read a value from, easier to see the shape of; useful for
   finding where something interesting happens before plotting it properly.

.. figure:: Exchangerdistribution.svg
   :alt: Percentage of exchange sites held by calcium, sodium and potassium along the column at one time
   :align: center

   **Fix the time, vary the place.** The exchanger composition along the
   column at step 12, as percentages of the sites.

   This is the complement of the first figure and the one that explains it.
   The breakthrough curve shows what came *out*; this shows what the column
   is *holding*, and the replacement of sodium and potassium by calcium
   moving along as a front is the mechanism behind the effluent curve.

.. figure:: TernaryCationExchangerTimeEvolution.svg
   :alt: Exchanger composition of four cells plotted as paths on a ternary diagram
   :align: center

   **Drop the axes entirely.** The three exchangeable cations sum to 100 %,
   so their composition is two independent numbers and fits on a ternary
   diagram. Each cell traces a path across it as time passes.

   Four cells are drawn -- 1, 10, 20 and 40. Their paths lie close to one
   another, which says that every part of the column passes through
   essentially the same sequence of exchanger compositions, just at different
   times. That is a statement about the *process* rather than about any one
   location, and none of the four figures above can make it.


The table
---------

.. csv-table:: table_ex1
   :file: table_ex1.csv
   :header-rows: 1
   :delim: ;

Results are also available as a table, which is what to use when a number is
wanted rather than a shape.


What it shows
-------------

That choosing a plot is choosing a question. The same results support a
breakthrough curve, a profile, a map and a composition path, and each
discards something the others keep.


Source
------

* Parkhurst, D. L. and Appelo, C. A. J. (2013). *Description of input and
  examples for PHREEQC version 3.* U.S. Geological Survey Techniques and
  Methods, book 6, chapter A43. The model is Example 11 of that manual.
* Appelo, C. A. J. and Postma, D. (2005). *Geochemistry, Groundwater and
  Pollution*, 2nd edition. Balkema, Leiden.